Blazin' Forth contains an extensive implementation of Turtle Graphics which supports all of the graphics modes of the 64, and is also by far the fastest turtle graphics implementation I have ever seen on this computer. I am particularly proud of this aspect of Blazin' Forth, and I hope you get a lot of pleasure out of it.
Turtle Graphics was developed by Seymour Papert of MIT as part of his Logo language, and it is an excellent way to explore computer graphics. The Turtle in Turtle Graphics is a graphics cursor, generally shaped like a triangle (shaped like an arrow-head in Blazin' Forth). You control the turtle by telling it to move FORWARD, or BACK , and as it moves, it draws a line. You control the turtles direction by giving it commands like RIGHT or LEFT. You can also use coordinates, through the SETXY command.
The graphics screen in Blazin' Forth is 240 turtle steps high ( screen coordinates 0 to 239) and 320 turtle steps wide ( screen coordinates 0 to 319). Wraparound, which is usually part of Turtle Graphics systems, is not implemented, since I think it's preferable to see part of a figure instead of a mess. The lines drawn by the turtle are therefore clipped. It should also be mentioned that the graphics screen does not take any of the memory normally available to Forth due to the intensive use made of the C64's powerful bank switching feature.
DRAW
Sets up the graphics screen, with the turtle in the center of the screen, pointing straight up. Defaults to SCOLOR and SPLITSCREEN , but these may be changed. It is extremely important that this word (or SCOLOR or DCOLOR) be used at least once before typing any of the other graphics words!
FD or FORWARD
Takes a number on the stack and moves the turtle forward that distance. Draws a line if the turtles pen is down. Example:
20 FD ( move the turtle 20 turtle steps forward)
BK or BACK
Takes a number on the stack and moves the turtle back that distance. Draws a line if the pen is down. Example:
20 BK ( move the turtle 20 turtle steps back)
RT or RIGHT
Takes a number on the stack, and rotates the turtle right that number of degrees. Example:
90 RIGHT ( rotate the turtle 90 degrees to the right)
LT or LEFT
Takes a number on the stack, and rotates the turtle left that number of degrees. Example:
90 LT ( rotate the turtle 90 degrees to the left)
*fp0
SP or SPLITSCREEN
Enters SPLITSCREEN mode, with 5 lines of text on the bottom of the screen, and the rest of the screen in graphics mode. This is the default condition. Due to the location of the hires screen, a small amount of flicker may be observed, particularly when the turtle is in the region of the split. This is a hardware limitation over which I have no control. Sorry.
FS or FULLSCREEN
Exits SPLITSCREEN mode. The entire graphics screen is displayed. Note that if you want to mix music and graphics, you must be in FULLSCREEN mode. This is because both splitscreen mode and the music words are interrupt driven.
NOSPLIT
This will cause DRAW to default to FULLSCREEN mode. Executing SPLITSCREEN will restore SPLITSCREEN as the default condition.
BG or BACKGROUND
Takes a number on the stack, and sets the background color of the hires screen to that color. When in splitscreen mode, the border color will also be affected by this command. The number should be between 0 and 15, as described in the programmers reference guide. Example:
1 BG ( sets background to white)
PC or PENCOLOR
Takes a number on the stack, and sets the pencolor of the turtle to that color. Note that a pencolor of -1 is allowed, and will cause the turtle to erase, instead of draw. Example:
2 PC ( draw in red)
PE or PENERASE
Causes the turtle to erase instead of draw as it moves. Note that the pen must be down in order to erase. (Or the eraser must be down, in this case.)
PU or PENUP
Lifts the turtles pen. The turtle may be moved without drawing or eraseing a line.
PD or PENDOWN
Sets the turtles pen down. The turtle will once again draw a line as it moves.
HT or HIDETURTLE
Makes the turtle invisible. Note that a pleasant side effect of this is that drawing will become even faster.
ST or SHOWTURTLE
Makes the turtle visible.
SCOLOR
Enters single color or HIRES mode. In this mode, all colors are available, but drawing over lines drawn in one color with a line in another color will change a small portion of the previous line to the new color. Lines have a finer, sharper appearance in this mode. Note that executing either SCOLOR or DCOLOR will have the same effect as DRAW - the screen will be cleared, and the turtle moved to its home position.
DCOLOR
Enters double color mode. In this mode, up to three lines of different colors may share the same area without conflict. Lines are thicker, but the colors are easier to see. Note that when in DCOLOR mode, scrolling of the text screen underneath the draw screen may affect certain of the colors. Since splitscreen mode is usually used only when debugging, this should not be a serious problem. (It's due to the sharing of color memory between the text screen and the hires screen.) Once DCOLOR has been selected, draw will default to this mode until SCOLOR is once again executed.
HOME
Sends the turtle to its home - center screen, pointing straight up. Note that the turtle will draw a line if the pen is down. (see: WINDOW)
SETXY
Takes two values from the stack - the X and Y coordinates of a point, and moves the turtle to that location, drawing a line if the pen is down. Example:
100 100 SETXY ( move the turtle to 100 100 )
SETH or SETHEADING
Takes a number on the stack which sets the current heading of the turtle. 0 degrees is pointing straight up, with degrees increasing to the right. Example:
90 SETH ( aim turtle at the right of the screen)
G$
Takes the address of a text string, and two coordinates. G$ then types the textstring on the graphics screen. The characters are not drawn by the turtle, and so the turtles position and heading are not affected. The only commands which affect both the turtle and G$ are PC ( except -1 PC , which has no effect on G$) and WINDOW. Characters drawn in DCOLOR mode are not very legible, incidentally. Example:
" THIS IS A STRING" 100 100 G$ ( type string starting at 100 100)
WINDOW ( x1 y1 x2 y2 -- )
Sets up a drawing window for the turtle. Takes four entries from the stack. x1 and y1 are the coordinates of the lower left corner of the drawing window, while x2 and y2 are the coordinates of the upper right hand corner of the drawing window. Executing this command will cause the turtle to center itself inside the window, and, although the turtle can move outside of the window, lines will be drawn only within the window boundary. Note that G$ is also affected by this command. HOME will center the turtle at its new home, but DRAW will reset the window to its maximum. Note that an error occurs if the coordinates passed to WINDOW are outside of the current window. An example of windowing is provided on the source disk. Make sure the disk is mounted, and then type 130 LOAD .
RESWIND
Calling this word will reset the turtle window to its default condition. This word must be used if you intend to set up multiple windows, since the new window will likely be outside of the old one, and therefore cause an error. Example:
: WINDOW1 RESWIND 0 0 50 50 WINDOW ;
: WINDOW2 RESWIND 100 100 150 150 WINDOW ;
The following are variables which may be accessed to determine the state of the turtle.
XCOR YCOR These are system variables which contain the current X coordinate andd Y coordinate of the turtle. Note that these variables should only be used to determine the coordinates of the turtle. Storing values in these variables will have strange effects. If you want to change the turtles position, you should use SETXY . Example:
XCOR @ YCOR @ . . ( display the current xy coordinates of the turtle.)
HEADING This contains the current heading of the turtle, in degrees. 0 is straight up, increasing to the right. The same caution applies as for XCOR YCOR . If you want to change the turtles heading, use SETH or SETHEADING. Example:
HEADING @ . ( print the turtles heading on the screen)
PENSTATE True if pen is down.
TURTLESTATE True if turtle is visible.
Don't be misled by the apparent simplicity of turtle graphics. It is extremely powerful, and allows many remarkable pictures to be drawn, as well as many interesting mathematical explorations to be carried out. It's also a *lot* of fun. As a simple example, here is a word that takes one value from the stack, and draws a square with sides of that length:
: SQUARE ( SIDE -- )
4 0 DO DUP FD 90 RT LOOP DROP ;
To try out this word, type DRAW and then 100 SQUARE. A square of 100 turtle units per side will be drawn.
This is obviously a simple example, but the power of turtle graphics, combined with the speed and power of Forth, allow amazingly rich and complex graphics displays to be drawn with words that are barely more complex than our SQUARE definition. As another example, here is a word that trues a truly remarkable curve:
: C-CURVE ( SIDE LEVEL )
?DUP 0= IF FD EXIT THEN
2DUP 1- RECURSE
90 RT
2DUP 1- RECURSE
90 LT 2DROP ;
This innocent looking definition draws a real whopper of a curve. To try it out, type DRAW, and then issue the following sequence of commands to orient the turtle:
70 BACK CLEARSCREEN FULLSCREEN 90 LEFT 3 10 C-CURVE
This type of curve is known as a fractal, which have received a lot of attention recently in the popular press. They have the reputation of being *very* hairy. Note the simplicity of the definition, and note also that Turtle Graphics and recursion are naturals when used together. I hope this brief introduction will encourage you to explore turtle graphics further on your own. There are some other programing examples included on the source disk. Aside from the windowing demo mentioned earlier, there are:
Another fractal, the DRAGON curve. This program draws a whole family of Dragons. Access this by typing 137 LOAD.
Space-filling curves. The famous HILBERT curve is here, as is the less well know but very pretty and interesting SIERPINKSI curve. To view these curves, type 135 136 THRU. The dragon curve, and both of these curves, are further examples of recursive programming in Forth.
There is a simple example of the use of DCOLOR mode. Access this by typing 131 133 THRU.
All of the above will run when they are loaded. In addition, there are some examples included which you may play around with interactively. Block 131 contains some words which draw circles. Screen 134 contains some words which use these words to build up more complex designs. First type 131 LOAD, and then 134 LOAD. The words available are:
SPINSHRINK Type DRAW SPINSHRINK to see this design.
The next two words require you to place a parameter on the stack.
SLINKY requires a value on the stack, which determines the radius of the circles drawn.
SPINSLINKY requires the same value. (This is a particularly pretty display.)
Finally, screen 138 contains three examples which deal with polygons. These are quite famous among turtle graphics users, and they are presented here to show you one way to implement them in Forth, or to introduce you to them, if you haven't met them before. Typing 138 LOAD will compile the following words:
POLY This word requires two values on the stack, which specify a side length and an angle. POLY draws closed polygons, and any polygon may be drawn by POLY. For example DRAW 100 90 POLY will draw a square of 100 turtle units.
POLYSPI This word requires the same two parameters on the stack as POLY, but POLYSPI draws spiraling polygons. This is easier to see than it is to describe. For example, DRAW 1 90 POLYSPI will draw a spiraling square (or SQUIRAL).
INSPI This word also requires two values on the stack, but where POLYSPI increased the side each time, INSPI increases the angle. An incredible variety of shapes can be drawn with both INSPI and POLYSPI. One of my favorite INSPI designs is DRAW 10 1 INSPI . You will no doubt discover others you like, as you try out the effects of different stack values on each of these words.
Blazin' Forth also contains words that allow you to manipulate sprites. Blazin' Forth will take care of most of the hardware details for you, but some caution must be exercised. Since you must setup your own sprite data areas, it is possible to garbage the disk buffers with your sprite data. However, with a small amount of care, this should not occur, since there is enough room for 45 sprites without stealing any room from Forth. (A total of 109 sprite images are available.)
You should first enter a sprite definition into the Forth dictionary. The method you use to do this is up to you. One possibility is to use C, as follows:
CREATE SPRITE1 0 C, 2 C, etc.
Or you can use the " word, if the string handlers are loaded into the system:
: SPRITE1 "ANCND" etc. ;
Note that if you use this second way, then you must add 1 to the address left by " , since the address left by " is the address of the strings count byte, and SETSHAPE , which is the word used to transfer the data to the sprite areas, expects the address of the start of the data on the stack.
However you decide to do it, your sprite definitions must be 64 bytes long. There are 63 bytes of spirte display data, while the last byte is used by the system to set the sprites color mode. If the last byte is 0 , then the sprite will be a hires (single color) sprite. If the last byte is anything else, then the sprite will be a multicolored one.
Each sprite-shape is assigned a sprite number by the hardware. You must use a slight amount of care in setting your shapes, since it is possible to garbage your disk buffers, or to select an area which the system is already using for something else, such as the color storage for the graphics screen.
There are 45 shape numbers which are available to you and won't cause any conflicts anywhere. Shape-numbers from 64 to 94 or perfectly safe, as are shape numbers from 112 to 126. Sprite numbers greater than 126, or between 95 and 111 are not available at anytime.
In addition, the sprite shapes from 0 to 64 may be used, but this will cause garbage to be written to the disk buffers. There are two solutions to this problem. One is to make sure you always type EMPTY-BUFFERS after using the sprite words. The other way (and it's probably the easiest in the long run) is to lower the top of memory to hex $C000. (For information on how to do this, please see CONFIGURE.) Note that you may have to pair down the dictionary if you take this second route. In any case, I find it hardly likely you will need more than the 45 sprites already available to you - but if you do need the full 109 shapes, they are available to you for very little extra work.
Once you have your shape data safely installed in the dictionary, you are ready to go:
SETSHAPE ( addr shape# -- )
SETSHAPE takes the address of a sprite image, and a shape# and moves the sprite data to the proper area for the display of that sprite. Note that DRAW must have been executed at least once prior to using this word!
S1 S2 S3 S4 S5 S6 S7 S8
These words set the current sprite. Executing these words will determine which sprite is affected by other sprite words.
SPRITEON ( SHAPE# -- )
Takes a shape number from the stack, and sets the current sprite to that shape. It then turns on the sprite. Note that the sprite must be on screen to be seen.Example:
S1 65 SPRITEON ( set sprite1 to shape# 65, and turn it on.)
One way of using this word for effective animation effects is to use it to shift between sprite images for the same sprite:
: SWITCH S1 40 0 DO 65 SPRITE ON 70 SPRITEON LOOP ;
(Note that the above example will probably go much to fast for effective animation. It's just an illustration.)
SPR-DCOLOR ( c1 c2 -- )
Takes two color codes from the stack, and sets the multi-color sprite color registers to these values. Note that all multi colored sprites will share these colors. Sprites not in multicolor mode are unaffected by this command.
SPRITECOLOR ( c -- )
Takes a color code from the stack, and sets the the current sprite to that color. Example:
S2 0 SPRITECOLOR ( set sprite 2 to black)
HIDESPRITE
Hides the current sprite. Example:
S1 HIDESPRITE ( hide sprite 1)
SHOWSPRITE
Shows the current sprite, if it is on screen. Example:
S1 SHOWSPRITE
SPRITEXY ( X Y -- )
Sets x y position of current sprite. Coordinate values are the same as for the turtle. Note that negative values are legal, and will cause the sprite to move offscreen at the left or bottom. Example:
S1 -1 100 SPRITEXY ( move the current sprite one pixel off of the screen.)
WIDE-SPRITE ( flag -- )
If flag is true, the current sprite will be made wider. Example:
S1 TRUE WIDE-SPRITE ( make sprite 1 wider)
S2 FALSE WIDE-SPRITE ( make sprite 2 narrow)
HIGH-SPRITE ( flag -- )
Same as wide-sprite, but makes the current sprite taller or shorter. Example:
S3 TRUE HIGH-SPRITE ( make sprite 3 taller)
SPRITECOVER ( flag -- )
If flag is true, the current sprite will cover the background. If flag is false, the current sprite will be transparent. Example:
S1 TRUE SPRITECOVER ( have sprite #1 cover its background.)
SPRITEBANG ( -- flag)
Leaves a true flag if the current sprite has banged into another sprite, and a false otherwise. Note that sprites can bang into each other even when off screen. Example:
: MOVEIT S1 319 0 DO I 150 SPRITEXY SPRITEBANG IF " BOOM! " I 150 G$ LEAVE THEN
LOOP ;
DATABANG ( -- flag)
Same as SPRITEBANG, but leaves true if the current sprite has banged into non-sprite data on the screen. Note that sprites can bang into data even when off screen.
For more information on defining sprites, as well as more details on multi-colored sprites, please see the programmers reference guide.
